SFXedit 0.93 Documentation.

SFXedit 0.93 beta documentation.

This is a prerelease of an upcoming Starfox level editor application.

It contains some bugs and may corrupt your ROM file(s), so only use it on backups.

I don’t provide the ROM file, and don’t ask me where to find them.
I hope you are or were once a proud StarFox cartridge owner.

It can -only- be used with version 1.0 of the Starfox ROM.
Version 1.0 has a red contour over the title screen logo.
Version 1.2 has a brown contour.
Japanese version has a blue contour.

I’ll add support for these other versions some day (including SFX Competition).

New in SFXedit 0.93: the program will check for the correct StarFox US 1.0 version.
If the version is not US 1.0, the program will tell you what version you were trying to open.
Just click the open ROM file button again and chose the correct version.

Now for an explanation of the level editor basics. Hexadecimal knowledge is required.

There are 2 banks used for the level in the game at $000005 and $00000D.
Most if not all hex adress used in the editor are in reverse byte order, and
that may change in the future.

The real ROM addresses of these can be found by multiplying the high byte by
32768 and then adding the remaining 16-bit chunk +512

The editor will edit an extra 32k bank at $000020 provided you extended
the ROM by at least 32k (32768 bytes). The extra empty bank must be filled
with FFs so to extend a SNES ROM, just add at least a 32768 bytes chunk of FFs.
The editor will auto-detect if the ROM has been extended.

I’ll add the possibility too access more extra banks soon.

In the editor you can
-Select multiple objects using the shift key.

-Copy them and paste them in empty spaces.

-Delete objects to free space.

-Please note that empty spaces (FF) will crash the game if it reads them.

-That’s why I suggest you work in the extra bank instead of trying to modify
the original levels too much.

-The “Open ROM” button is used to open a ROM.

-The “Run in SNES9x” should open the ROM in your Emulator.

-This run function may or may not work :)

-The revert file location is only asked if it’s needed (when you revert an object)

-The revert file location is reseted when you open a save/edit ROM.

-”Revert Selection” only works on objects that have the same type in the revert ROM.

-Click on a location in the blue list to jump to other levels, default is Training.

-You can edit any property of any object that has it’s value hi-lighted by
clicking on it. You can even edit the br1, br2, br3 and b4 properties of h78
asm objects without having to edit the code.

-Very important feature: if you click on an editable property name,
many properties will display a pop-up menu, where you can chose pre-defined
values with descriptions, very useful for objnum:, objtyp: , objid: and bhnum:.

-If you click on “warp:” or “br1:” property though. the editor will jump to the warp
address. Use the Go Back button to get back to where you where.

-When “duplicate at:” is selected, the duplicate button will duplicate objects
starting at the next empty space found after the address (default is “000020”
the start of the empty extra bank)

-If the next empty location is too far or there is not enough space there,
the editor will spit out an error.

-Most levels are initialized in the 0D bank but jump back in the 05 bank, you
can use this warp object to jump to a new level at the 20 bank for example.

-To create new objects, you can choose them by clicking the popup menu field at
the right of the “new object” button, then click the button.

-To paste and create objects, you must select an empty byte object that is
followed by enough empty bytes objects to fit the object length.

-When you click on the animated icon for an object it will open it in the 3d
viewer on top.

-You can rotate objects in the 3d viewer by dragging in the 3d view, holding
alt will rotate on another axis.

-You can use the “.” and “,” keys to step frames of an object when the
animation is stopped.

-When you click on the asm property of an h78 chunk, you get a disassembled
version of the included asm code in the red upper right text field.

-You can set initial conditions for the register emulation bits, most h78 chunk
don’t require a change from the default. (this only affects disassembling)

-If you click the Hex Data Mode button, you’ll get an hexdata: property field
for objects instead of the individual properties.

-The hexdata: property fields contains raw hex bytes not including the first
byte which is the “objtyp:” byte.

-You can copy and paste values when they are selected. You can even copy some
uneditable properties like “addr:” to a “warp:” property.

-Click on “Normal Mode” to get the normal view of properties.

The ztimer value is a decrementing counter that is very important to the game
engine. Until this counter reach zero, the games moves forward without drawing
and loading anything new.

When the value reaches zero, the next object is loaded and displayed if it’s a
polygon object. The game will then load and draw any following objects at a
position relative to the current one, until it reaches a new ztimer setting.

The h8A and h12 objects are used to set the ztimer, but most objects with
x y z coords also can set the ztimer.

It’s used to make gaps in game, it makes the x y z coord system always
relative to the last ztimer setting.

The object viewer is new in version 0.93.

Click the "object viewer" button to open it.

-You get access to the same 3d and animation controls as in the level editor's mini viewer.

-The list of objects in the blue text fields at the right is referring to all documented objects.

-Clicking on the blue text field will open and view the object.

-Descriptions are preliminary, and some objects are not displayed and texture support is minimal.

-The "export to .obj file" button will save a monochrome Wavefront .OBJ format file
from the current object in view. The .OBJ file is saved in the application's enclosing folder.
Animated objects will create multiple .OBJ files when exporting.

-The color palette buttons will switch the palette for the current object, changes are not saved.

-At the bottom of the object viewer interface is the 28 bytes header that exists for every 3d
object in Starfox.It includes information about where to find the polygon mesh data, scaling,
palette set and other info which I didn't manage to figure out yet (I suspect those are about
collision regions).

-You cannot save changes to this header data for now using the editor, but obviously,
I'm planning to add support for header editing.

-Note the object viewer is not an object editor (not yet!) so nothing you change in it will
have any impact on the level editor and your ROM file.

-To get back to the level editor from in the object viewer, click the "Level Editor" button.(duh!)

To be added in a future release is text editing so the you can edit text found
in the game like dialogs, bosses and level descriptions.

I'm aiming to implement a WYSIWYG 3d editor that will be much more interactive than
the current text/menu based editor.

Still this part of the interface will still be needed to allow a more complete control of
what can happen in the game like loops, warps, music and other events.

I'm also planning to add an "easy mode" where people won't have to deal with hexadecimal.

Still many of the original levels are complicated by themselves and even an easy to use
editor won't help with those.

Until then, you can experiment on your own with the editor, which is overall useable once
you figure out the basics of it :)

Here are descriptions for all chunk types used in the game.

h86 len: 14 Object+behavior with 16 bits coords

This is one of the common way to display 3d polygonal objects in the game.16-bits x y and z coordinates are used (-32768 to +32768)

objad: uses 2 bytes to refer to a polygonal object.

bhaddr: uses 3 bytes to refer directly to a behavior.
A pop-up menuis also available for this property with all the values used in the game

h00 len: 11 Object+behavior with 16 bits coords

This one also uses 16 bits coordinates.

Instead of the objad: property, objnum: is used to refer to the
polygon object. This restricts you to 256 predefined values.

The objad: property is not editable in this chunk type.
It's being displayed for reference.

Much the same, bhnum: replaces bhaddr: in h00 chunks,
and only bhnum: is editable and is restricted to 256 predefined values.

h74 len: 10 Object/behavior with 16 bits coords

This chunk type also uses 16 bits coords .

It uses only one byte (bhnum:) to refer to a polygon object and a behavior at the same time.

Each bhnum: value has an associated 1 byte value referring to a polygon object.

You can see this value in the non editable objnum: text field.

h70 len: 7 Object+behavior with 8 bits coords

This chunk type is like h00 but with 8 bits coordinates.

The z coordinate is ranging from 0 to 255 (so they are only positive) when 8 bits coords are used.

objnum: is used to refer to the polygonal object (one byte).
bhnum: is used to refer to a predefined behavior (one byte).

bhaddr: and objid: are non editable in h70, their values can be
copied and pasted in other editable bhaddr: and bhnum: fields.

h76 len: 6 Object/behavior with 8 bits coords

This chunk type is like h86 but with 8 bits coordinates.

h0A len: 16 Random group behavior with 16 bits coords

This chunk type has 16 bits x, y and z coordinates.
It also contains a 5 bytes random_group: property.
The main use of this object is to generate multiple objects
at random or semi random position.

It's used to generate asteroid fields and other randomized swarms.

Click on the random group property to get a pop-up menu
with all the known types with descriptions.

The objad: property is a 2 bytes value referring to polygon objects.
It's not always used by the h0A depending on the swarm type.

All the previously described polygon objects chunk types include
a ztimer: property, which is defined earlier in the document.

h78: len:varies. Pure ASM code block.

This chunk type will execute imbeded SNES code and then go back to the game.

When you click on the asm: property, the code will get disassembled in the red asm text field.

You can only observe the listing, not edit it. Note that RTL in a h78 block means "go back to the game" and the command before,
usually LDX is used to determine the jump back address.

If you really think you can edit the raw code, you can use the Hex Data mode.

The editor will try to automatically find those "branches"
and make them editable in the br1: br2: br3: and br4: field.

The brx: properties will refer to 2 bytes addresses in the
current bank ie: XXXX05, XXXX0D or XXXX20.

h2C len: 6 Warp to 2 bytes address in current bank.

This chunk type is used to warp to a 2 bytes address in the current bank, but only when a predefined condition is met.

The condition: property is 3 bytes long and refers to a specific address where the condition is checked.

You can use the included pop-up menu to access all the values that are used in the game.

For example it's used in the Spaceship Armada level to decide if the arwing will enter inside a ship or pass beside it.

It's also used to loop bosses level parts until they are destroyed.

h5E len: 6 Screen transition

Transitions and other unknown events.

Use the pop-up menu to get a list of values used in the game.

h04 len: 5 Loop segment x times

Used in the game loop to any address in the current bank using 2 bytes ie: XXXX05, XXXX0D or XXXX20. The loop will occur X number of times then the game will continue with the next object.

Note that when moving/duplicating parts of levels you have to manually change the destination address for h04 loops, and other warps like h2E and h28, and h78 brx: warp properties.

h36 len: 4 Rotates previous polygon object

Will rotate the last displayed polygon object according to a one byte rotation mode and 2 bytes angle or rotation speed value.

Modes include static rotation to specific angles on each of the 3 axis's. There are also animated modes were an object rotates by itself on a given axis at a given speed.

The pop-up menu for this one needs to be completed.

h2E len: 4 Warp to 3 bytes address

h28 len: 4 Warp to 3 bytes address, add to stack

These chunk objects will warp to anywhere in the ROM
it uses the same 3 bytes format as the addr: field.

You can even copy and paste those addresses between chunks.
The difference between the two types is that h28 is a special warp
object that remembers where it got launched from. When a h2A object is reached, the game jumps back to this stored address.

Jump back addresses are added to a "stack" so that you can use
multiple h28 warps and get back to the point where you left by using the same amount of h2A objects. If you use a h2A while being in the lowest level of the stack, the game will exit the level and return to the level selection screen.

There is a fixed limit to the "recursion" that you can have.
For example, if you use a h28 warp to loop a level endlessly with no
h2A objects inside the loop, the game will freeze after a few dozens
of loops. So don't do that :)

h2E warps can be used over and over and anywhere in the game.
They don't use h2A objects so if you want to jump back you have to
do it manually using another h2E object.

The h28 and h2E objects are the key to create new levels, use themto jump to empty spaces.

Most levels start with initialization chunks in bank "0D" then warp
to the main level data in bank "05" using a h28 object.

You can have this address point to any part of the game, including new levels you created in the empty spaces.

Just use a h2A object at the end of your level data so that the game ends the level normally.

h10 len: 3 Setup Level BG, Music etc.

Basic initialization of the level, changes the background graphics,
the music and other aspects such as the flight mode.

h8C len: 3 Behavior for previous object (16-bits)

This chunk type attaches to the last showed polygonal objects and
is used to give it a complicated behaviors that are the basis of the game.

Those behaviors are not the same as one used inside the polygon object chunks.

These behaviors includes: Flying on many complicated paths, sometimes shooting different types of lasers aimed at Fox.

Characters dialog can be triggered. Many "plots" are setup using h8C chunks. For example one behavior puts an enemy coming from far away, attacking you. If you don't shoot it, a teammate will fly by and shoot it for you, blabbering something about it.

There are different sets of these and many are character specific
ie: Slippy is taking more time to rescue you, Falco is the fastest and will brag about it if you don't beat him at it.

There are also "pairs" of behaviors,one to be applied to an Arwing polygonal object and the other to an enemy object. They are used to create scenarios where one is chasing the other.

All the dialog like "Thank you Fox for saving me bla bla bla" , "ouch!" or "I was gonna get that one!" happens automatically.

There are many sets of these pairs using different paths. Other h86 behaviors includes the flying credits from the end.

Note that mostly h86 behaviors will use the polygon object on which
it is attached, but sometimes will override it with its own polygon object.

This chunk type also features a pop-up menu with descriptions and values for all the h86 behaviors used in the game.

h8A len: 2 Set ztimer with 8 bit value

h12 len: 3 Set ztimer with 16 bit value

Sets the ztimer to a 8 bit or 16 bit value.

The game will move forward without displaying nor loading new chunks until the ztimer reaches zero.

Used to make level gaps and time delays in the game.

h64 len: 2 Init camera?

It's found only at the start of level and seems to reset the camera.
Is always followed by h66.

h76 len: 6 Object/behavior with 8 bits coords

This chunk type is like h86 but with 8 bits coordinates.

h14 len: 2 Changes Music

To change the music anywhere in a level. Value "F0" fades out.
No pop up menu yet.

h2A len: 1 Jump back from warp

As described in the h28 explanation, will make the game jump back to just after the last h28 was called.

If used at the "bottom" of the stack, when no h28 have been used, the game will exit the level and get back to the level selection screen.

h5A len: 1 Palette set change?

I'm not too sure about this one but it seems to override the palette set for the previous object.

h02 len: 1 Fades music out then loops empty level

Used at the end of some levels?

h0E len: 1 Shows current stage number

Displays "STAGE: X"

h44 len: 1 Fades to black

Fades the screen to black.

h84 len: 1 Palette set change?

Not sure about this one yet.

h4E len: 1 Unknown use.

This chunk type is one byte and I don't know its use yet.